Skip Headers

Oracle® C++ Call Interface Programmer's Guide 10g Release 2 (10.2) Part Number B14294-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# Bfile Class

The `Bfile` class defines the common properties of objects of type `BFILE`. A `BFILE` is a large binary file stored in an operating system file outside of the Oracle database. A `Bfile` object contains a logical pointer to a `BFILE`, not the `BFILE` itself.

Methods of the `Bfile` class enable you to perform specific tasks related to `Bfile` objects.

Methods of the `ResultSet` and `Statement` classes, such as `getBfile()` and `setBfile()`, enable you to access an SQL `BFILE` value.

The only methods valid on a `NULL` `Bfile` object are setName(), isNull(), and operator=().

An uninitialized `Bfile` object can be initialized by:

- The setName() method. The `BFILE` can then be modified by inserting this `BFILE` into the table and then retrieving it using `SELECT` ... `FOR UPDATE.` The `write()` method will modify the `BFILE`; however, the modified data will be flushed to the table only when the transaction is committed. Note that an insert is not required.

- Assigning an initialized `Bfile` object to it.

  See Also: In-depth discussion of `LOB`s in the introductory chapter of Oracle Database Application Developer's Guide - Large Objects,

Table 12-7 Summary of B file Methods

Method | Summary
--- | ---
Bfile() | `Bfile` class constructor.
close() | Closes a previously opened `BFILE`.
closeStream() | Closes the stream obtained from the `BFILE`.
fileExists() | Tests whether the `BFILE` exists.
getDirAlias() | Returns the directory object of the `BFILE`.
getFileName() | Returns the name of the `BFILE`.
getStream() | Returns data from the `BFILE` as a `Stream` object.
getUStringDirAlias() | Returns a `UString` containing the directory object associated with the `BFILE`.
getUStringFileName() | Returns a `UString` containing the file name associated with the `BFILE`.
isInitialized() | Tests whether the `Bfile` object is initialized.
isNull() | Tests whether the `Bfile` object is atomically `NULL`.
isOpen() | Tests whether the `BFILE` is open.
length() | Returns the number of bytes in the `BFILE`.
open() | Opens the `BFILE` with read-only access.
operator=() | Assigns a `BFILE` locator to the `Bfile` object.
operator==() | Tests whether two `Bfile` objects are equal.
operator!=() | Tests whether two `Bfile` objects are not equal.
operator==() | Reads a specified portion of the `BFILE` into a buffer.
setName() | Sets the directory object and file name of the `BFILE`.
setNull() | Sets the `Bfile` object to atomically `NULL`.

## Bfile()

`Bfile` class constructor.

Syntax | Description
--- | ---
    Bfile();
| Creates a `NULL` `Bfile` object.
    Bfile(
       const Connection *connectionp);
| Creates an uninitialized `Bfile` object.
    Bfile(
       const Bfile &srcBfile);
| Creates a copy of a `Bfile` object.

Parameter | Description
--- | ---
    connectionp
| The connection pointer
    srcBfile
| The source `Bfile` object

## close()

Closes a previously opened `Bfile`.

Syntax

    void close();

## closeStream()

Closes the stream obtained from the `Bfile`.

Syntax

    void closeStream(
       Stream *stream);

Parameter | Description
--- | ---
    stream
| The stream to ne closed.

## fileExists()

Tests whether the `BFILE` exists. If the `BFILE` exists, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool fileExists() const;

## getDirAlias()

Returns a string containing the directory object associated with the `BFILE`.

Syntax

    string getDirAlias() const;

## getFileName()

Returns a string containing the file name associated with the `BFILE`.

Syntax

    string getFileName() const;

## getStream()

Returns a `Stream` object read from the `BFILE`. If a stream is already open, it is disallowed to open another stream on the `Bfile` object. The stream must be closed before performing any `Bfile` object operations.

Syntax

    Stream* getStream(
       unsigned int offset = 1,
       unsigned int amount = 0);

Parameter | Description
--- | ---
    offset
| The starting position at which to begin reading data from the `BFILE`. If `offset` is not specified, the data is written from the beginning of the `BLOB`. Valid values are numbers greater than or equal to `1`.
    amount
| The total number of bytes to be read from the `BFILE`; if `amount` is `0`, the data will be read in a streamed mode from input `offset` until the end of the `BFILE`.

## getUStringDirAlias()

Returns a `UString` containing the directory object associated with the `BFILE`.

Note: The `UString` object is in UTF16 character set. The environment associated with `BFILE` should be associated with UTF16 charset.

Syntax

    UString getUStringDirAlias() const;

## getUStringFileName()

Returns a `UString` containing the file name associated with the `BFILE`.

Note: The `UString` object is in UTF16 charset. The environment associated with `BFILE` should be associated with UTF16 charset.

Syntax

    UString getUStringFileName() const;

## isInitialized()

Tests whether the `Bfile` object has been initialized. If the `Bfile` object has been initialized, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool isInitialized() const;

## isNull()

Tests whether the `Bfile` object is atomically `NULL`. If the `Bfile` object is atomically `NULL`, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool isNull() const;

## isOpen()

Tests whether the `BFILE` is open. The `BFILE` is considered to be open only if it was opened by a call on this `Bfile` object. (A different `Bfile` object could have opened this file as more than one open can be performed on the same file by associating the file with different `Bfile` objects). If the `BFILE` is open, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool isOpen() const;

## length()

Returns the number of bytes (inclusive of the end of file marker) in the `BFILE`.

Syntax

    unsigned int length() const;

## open()

Opens an existing `BFILE` for read-only access. This function is meaningful the first time it is called for a `Bfile` object.

Syntax

    void open();

## operator=()

Assigns a `Bfile` object to the current `Bfile` object. The source `Bfile` object is assigned to this `Bfile` object only when this `Bfile` object gets stored in the database.

Syntax

    Bfile& operator=(
       const Bfile &srcBfile);

Parameter | Description
--- | ---
    srcBfile
| The `Bfile` object to be assigned to the current `Bfile` object.

## operator==()

Compares two `Bfile` objects for equality. The `Bfile` objects are equal if they both refer to the same `BFILE`. If the `Bfile` objects are `NULL`, then `FALSE` is returned. If the `Bfile` objects are equal, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool operator==(
       const Bfile &srcBfile) const;

Parameter | Description
--- | ---
    srcBfile
| The `Bfile` object to be compared with the current `Bfile` object.

## operator!=()

Compares two `Bfile objects` for inequality. The `Bfile` objects are equal if they both refer to the same `BFILE`. If the `Bfile` objects are not equal, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool operator!=(
       const Bfile &srcBfile) const;

Parameter | Description
--- | ---
    srcBfile
| The `Bfile` object to be compared with the current `Bfile` object.

## read()

Reads a part or all of the `BFILE` into the buffer specified, and returns the number of bytes read.

Syntax

    unsigned int read(
       unsigned int amt,
       unsigned char *buffer,
       unsigned int bufsize,
       unsigned int offset = 1) const;

Parameter | Description
--- | ---
    amt
| The number of bytes to be read. Valid values are numbers greater than or equal to `1`.
    buffer
| The buffer that the `BFILE` data is to be read into. Valid values are numbers greater than or equal to `amt`.
    buffsize
| The size of the buffer that the `BFILE` data is to be read into. Valid values are numbers greater than or equal to `amt`.
    offset
| The starting position at which to begin reading data from the `BFILE`. If `offset` is not specified, the data is written from the beginning of the `BFILE`.

## setName()

Sets the directory object and file name of the `BFILE`.

Syntax | Description
--- | ---
    void setName(
       const string &dirAlias,
       const string &fileName);
| Sets the directory object and file name of the `BFILE`.
    void setName(
       const UString &dirAlias,
       const UString &fileName);
| Sets the directory object and file name of the `BFILE` (Unicode support). The client `Environment` should be initialized in OCCIUTIF16 mode.

Parameter | Description
--- | ---
    dirAlias
| The directory object to be associated with the `BFILE`.
    fileName
| The file name to be associated with the `BFILE`.

## setNull()

Sets the `Bfile object` to atomically `NULL`.

Syntax

    void setNull();